feat(ui): Mosaic field component by austincalvelage · Pull Request #9322 · clerk/javascript

austincalvelage · 2026-08-04T01:04:04Z

Description

https://swingset-git-mosaic-text-field-component.clerkstage.dev/components/field

Adds the Mosaic Field component:

Adds the compound Field.Root, Field.Label, Field.Description, and Field.Error API.
Connects labels, descriptions, and errors to a composed Mosaic control using generated or caller-provided IDs and the appropriate aria-* attributes.
Emits a consistent generated control and label relationship during server rendering; caller-provided control IDs and registered message relationships finalize during hydration.
Propagates invalid, disabled, and required to composed Mosaic inputs.
Provides styled error presentation with an alert-circle icon. Validation, error visibility, and lifecycle state such as dirty, touched, filled, and focused remain caller-owned.

import { Field } from '@clerk/ui/mosaic/components/field';
import { Input } from '@clerk/ui/mosaic/components/input';

<Field.Root required>
  <Field.Label>Email address</Field.Label>
  <Input
    name='email'
    type='email'
  />
  <Field.Description>Used for account notifications.</Field.Description>
</Field.Root>;

changeset-bot · 2026-08-04T01:04:09Z

🦋 Changeset detected

Latest commit: 1bcc702

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-08-04T01:04:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 11, 2026 8:29pm
swingset	Ready	Preview	Aug 11, 2026 8:29pm

pkg-pr-new · 2026-08-04T18:45:33Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9322

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9322

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9322

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9322

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9322

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9322

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9322

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9322

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9322

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9322

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9322

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9322

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9322

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9322

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9322

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9322

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9322

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9322

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9322

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9322

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9322

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9322

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9322

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9322

commit: 1bcc702

coderabbitai · 2026-08-06T13:38:26Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Added the Mosaic Field component with Root, Label, Description, and Error parts. Added context-based control IDs and ARIA relationships to Input. Added styling, an alert icon, public exports, SSR and interaction tests, Storybook documentation, and Swingset registry entries.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

clerk/javascript#9309: This PR extends the Mosaic Input component by integrating Field context and accessibility props.

Suggested reviewers: alexcarpenter, maxyinger

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: adding the Mosaic Field component.
Description check	✅ Passed	The description directly explains the new Field APIs, accessibility behavior, state propagation, and error presentation.

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 6

🧹 Nitpick comments (1)

packages/ui/src/mosaic/components/field/index.ts (1)
1-2: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove the new nested barrel file.

The new packages/ui/src/mosaic/components/field/index.ts re-export file conflicts with the repository rule that prohibits barrel files because they can create circular dependencies.

packages/ui/src/mosaic/components/field/index.ts#L1-L2: remove this barrel file.

packages/ui/src/mosaic/styles/index.ts#L17-L18: re-export Field and its prop types directly from ../components/field/field.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ui/src/mosaic/components/field/index.ts` around lines 1 - 2, Remove
the nested barrel file packages/ui/src/mosaic/components/field/index.ts (lines
1-2). Update the exports at packages/ui/src/mosaic/styles/index.ts (lines 17-18)
to re-export Field and its prop types directly from ../components/field/field.
Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/quiet-fields-compose.md:
- Around line 1-2: Replace the empty changeset frontmatter in
quiet-fields-compose.md with an `@clerk/ui` minor release entry, and add a concise
description of the new public Field compound component API.

In `@packages/swingset/src/stories/field.component.mdx`:
- Line 36: Update the Field description near the Field.Root usage note to remove
the claim that it does not propagate semantic state, while preserving the
statements that it does not validate controls or render errors automatically and
that its parts can be used independently.

In `@packages/swingset/src/stories/field.component.stories.tsx`:
- Line 1: Add the Emotion JSX import-source pragma at the beginning of the field
component story, before the existing Field import, so the styled Mosaic story
uses Emotion's JSX transform.

In `@packages/ui/src/mosaic/components/field/field.context.tsx`:
- Around line 4-10: Propagate disabled, required, and invalid state from
Field.Root to composed controls: in
packages/ui/src/mosaic/components/field/field.context.tsx lines 4-10, add typed
state fields to FieldContextValue; in
packages/ui/src/mosaic/components/field/field.tsx lines 20-37, add the states to
FieldRootProps and pass them through FieldProvider; in
packages/ui/src/mosaic/components/input/input.tsx lines 15-39, resolve explicit
control props before context values and apply the resulting disabled, required,
and aria-invalid attributes.
- Around line 67-74: Update the field context around the useSafeLayoutEffect
registration and the input relationship handling in
packages/ui/src/mosaic/components/field/field.context.tsx:67-74 and
packages/ui/src/mosaic/components/input/input.tsx:37-39 so generated Description
and Error IDs are derived during render rather than only populated by the
effect, while preserving client-side registration and cleanup. Add an SSR
assertion covering the generated aria-describedby relationships.

In `@packages/ui/src/mosaic/components/field/field.ssr.test.tsx`:
- Around line 48-62: Update Field.Root and its associated label/control ID
handling so an explicit Input id such as custom-control is preserved in SSR
markup and used for the label for attribute. Update
packages/ui/src/mosaic/components/field/field.ssr.test.tsx lines 48-62 to expect
custom-control in both locations, and update
packages/ui/src/mosaic/components/field/field.test.tsx lines 147-176 to verify
hydration preserves the server-rendered ID without adding it afterward.

---

Nitpick comments:
In `@packages/ui/src/mosaic/components/field/index.ts`:
- Around line 1-2: Remove the nested barrel file
packages/ui/src/mosaic/components/field/index.ts (lines 1-2). Update the exports
at packages/ui/src/mosaic/styles/index.ts (lines 17-18) to re-export Field and
its prop types directly from ../components/field/field.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: beecab09-0ad7-4c52-8e49-9ae6062c9e24

📥 Commits

Reviewing files that changed from the base of the PR and between 1799158 and e014d4e.

📒 Files selected for processing (14)

.changeset/quiet-fields-compose.md
packages/swingset/src/components/DocsViewer.tsx
packages/swingset/src/lib/registry.ts
packages/swingset/src/stories/field.component.mdx
packages/swingset/src/stories/field.component.stories.tsx
packages/ui/src/mosaic/components/field/field.context.tsx
packages/ui/src/mosaic/components/field/field.ssr.test.tsx
packages/ui/src/mosaic/components/field/field.styles.ts
packages/ui/src/mosaic/components/field/field.test.tsx
packages/ui/src/mosaic/components/field/field.tsx
packages/ui/src/mosaic/components/field/index.ts
packages/ui/src/mosaic/components/input/input.tsx
packages/ui/src/mosaic/icons/registry.tsx
packages/ui/src/mosaic/styles/index.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)
clerk/cli (auto-detected)

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/ui/src/mosaic/components/field/field.context.tsx (1)
117-136: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Preserve caller-provided control IDs during SSR.

Line 122 registers the supplied id only after commit. During SSR, context.controlId remains defaultControlId. Input then uses that value before its own id, so <Input id="email" /> renders with a generated ID and changes after hydration.

Derive the initial control ID during render, or provide it to FieldProvider before descendant rendering. Add an SSR test that verifies the input id and generated label htmlFor both use a caller-provided ID.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ui/src/mosaic/components/field/field.context.tsx` around lines 117 -
136, Update the control-ID derivation in the field context render path so a
caller-provided id is available during SSR, instead of relying only on the
post-commit registerControlId effect. Ensure descendants such as Input and
generated labels use that initial ID consistently, while preserving generated
IDs when no id is supplied. Add an SSR test covering both the rendered input id
and label htmlFor for a caller-provided ID.

🧹 Nitpick comments (1)

packages/ui/src/mosaic/components/field/field.tsx (1)
21-25: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document the exported props interface.

Add concise JSDoc for FieldRootProps. Document that its state props apply to composed controls through field context.

As per coding guidelines, “All public APIs must be documented with JSDoc.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ui/src/mosaic/components/field/field.tsx` around lines 21 - 25, Add
concise JSDoc immediately above the exported FieldRootProps interface,
documenting the interface and clarifying that its disabled, required, and
invalid state props apply to composed controls through field context.
Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/ui/src/mosaic/components/field/field.context.tsx`:
- Around line 117-136: Update the control-ID derivation in the field context
render path so a caller-provided id is available during SSR, instead of relying
only on the post-commit registerControlId effect. Ensure descendants such as
Input and generated labels use that initial ID consistently, while preserving
generated IDs when no id is supplied. Add an SSR test covering both the rendered
input id and label htmlFor for a caller-provided ID.

---

Nitpick comments:
In `@packages/ui/src/mosaic/components/field/field.tsx`:
- Around line 21-25: Add concise JSDoc immediately above the exported
FieldRootProps interface, documenting the interface and clarifying that its
disabled, required, and invalid state props apply to composed controls through
field context.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f801a372-56ed-4ed9-9d67-a21a6ba88cac

📥 Commits

Reviewing files that changed from the base of the PR and between 1ef2b96 and f592827.

📒 Files selected for processing (5)

packages/swingset/src/stories/field.component.mdx
packages/ui/src/mosaic/components/field/field.context.tsx
packages/ui/src/mosaic/components/field/field.test.tsx
packages/ui/src/mosaic/components/field/field.tsx
packages/ui/src/mosaic/components/input/input.tsx

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/cli (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)

🚧 Files skipped from review as they are similar to previous changes (3)

packages/swingset/src/stories/field.component.mdx
packages/ui/src/mosaic/components/field/field.test.tsx
packages/ui/src/mosaic/components/input/input.tsx

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 01:04 View deployment

github-actions Bot added the ui label Aug 4, 2026

vercel Bot deployed to Preview – swingset August 4, 2026 01:06 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 18:43 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 18:45 View deployment

austincalvelage force-pushed the mosaic-text-field-component branch from 57aeff6 to fd49235 Compare August 4, 2026 20:48

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 20:49 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 20:51 View deployment

austincalvelage changed the title ~~feat(ui):Mosaic text field component~~ feat(ui): Mosaic text field component Aug 4, 2026

austincalvelage changed the title ~~feat(ui): Mosaic text field component~~ feat(ui): Mosaic field component Aug 4, 2026

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 22:03 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 22:05 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 22:32 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 22:34 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 22:52 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 22:54 View deployment

austincalvelage force-pushed the mosaic-text-field-component branch from ca96e1b to a6c399c Compare August 4, 2026 23:01

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 23:02 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 23:03 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox August 4, 2026 23:10 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 23:12 View deployment

austincalvelage force-pushed the mosaic-text-field-component branch from ee83a6e to fcbd583 Compare August 5, 2026 03:25

vercel Bot deployed to Preview – clerk-js-sandbox August 5, 2026 03:26 View deployment

vercel Bot deployed to Preview – swingset August 5, 2026 03:28 View deployment

austincalvelage force-pushed the mosaic-text-field-component branch from fcbd583 to 374b29c Compare August 5, 2026 04:08

vercel Bot deployed to Preview – clerk-js-sandbox August 5, 2026 04:08 View deployment

vercel Bot deployed to Preview – swingset August 5, 2026 04:10 View deployment

Base automatically changed from austin/mosaic-input-component to main August 6, 2026 13:31

austincalvelage force-pushed the mosaic-text-field-component branch from b387d17 to e014d4e Compare August 6, 2026 13:31

vercel Bot deployed to Preview – clerk-js-sandbox August 6, 2026 13:32 View deployment

vercel Bot deployed to Preview – swingset August 6, 2026 13:34 View deployment

coderabbitai Bot reviewed Aug 6, 2026

View reviewed changes

austincalvelage force-pushed the mosaic-text-field-component branch from e014d4e to cfe215d Compare August 10, 2026 19:48

vercel Bot deployed to Preview – clerk-js-sandbox August 10, 2026 19:49 View deployment

vercel Bot deployed to Preview – swingset August 10, 2026 19:51 View deployment

austincalvelage force-pushed the mosaic-text-field-component branch from cfe215d to 1ef2b96 Compare August 10, 2026 22:01

vercel Bot deployed to Preview – clerk-js-sandbox August 10, 2026 22:01 View deployment

vercel Bot deployed to Preview – swingset August 10, 2026 22:03 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox August 11, 2026 16:14 View deployment

vercel Bot deployed to Preview – swingset August 11, 2026 16:16 View deployment

coderabbitai Bot reviewed Aug 11, 2026

View reviewed changes

austincalvelage added 14 commits August 11, 2026 10:40

feat(ui): add Mosaic TextField component

d70b43b

docs(swingset): add Mosaic TextField stories

c92cf03

docs(swingset): fix horizontal field example

8fc4aed

refactor(ui): replace TextField with semantic Field

6dd0ffd

docs(swingset): replace TextField stories with Field

a65f80b

fix(ui): align field description icon

0ece91e

docs(swingset): align Field docs with StyleX

bd5aea1

feat(ui): automatically associate Mosaic Field controls

3b9ac99

docs(swingset): document automatic Field associations

a883d28

fix(ui): align Field error icon to line height

131988d

fix(ui): align Field label color with Figma

594d6d7

feat(ui): propagate Field semantic state

5e8594a

docs(swingset): clarify Field semantic state

c234942

Add reset

1bcc702

alexcarpenter approved these changes Aug 11, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(ui): Mosaic field component - #9322

feat(ui): Mosaic field component#9322
austincalvelage wants to merge 14 commits into
mainfrom
mosaic-text-field-component

austincalvelage commented Aug 4, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 6, 2026 •

edited

Loading

Reviews paused

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

austincalvelage commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

changeset-bot Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

austincalvelage commented Aug 4, 2026 •

edited

Loading

changeset-bot Bot commented Aug 4, 2026 •

edited

Loading

vercel Bot commented Aug 4, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 4, 2026 •

edited

Loading

coderabbitai Bot commented Aug 6, 2026 •

edited

Loading